Open textbooks with Quarto and GitHub

Workshop for Education Support colleagues at the UU library

RDM Support

Content

  • Introducing R, RStudio, and Quarto
  • Basic set-up and GitHub publication of a Quarto book
  • ☕ BREAK
  • Text editing in Markdown
  • The git workflow
  • ☕ BREAK
  • Interactivity options (demo)
  • Publishing and archiving

R and RStudio

R logo

Programming language

RStudio logo

Pretty interface to interact with R
(and git, and Quarto)

The Rstudio interface

Quarto

“An open-source scientific and technical publishing system”

  • Turn text documents (.qmd) into html, pdf, epub, docx and more.

    Today: 💻 html (documents that can be hosted on the web)

  • Books 📖, but also: slides, blogs, articles, websites, and more.

Quarto: some history

  • Quarto = more extensive version of R markdown.

  • Rmarkdown: make science more reproducible.

  • Document (.Rmd) containing both R code (R) and text (markdown).

  • When rendering an R markdown document, all code gets executed as well.

  • Same for Quarto!

    But: more features + more recent than R markdown

Basic set-up of a book

💪 Let’s get to work!

Follow the steps here:

https://utrechtuniversity.github.io/open-textbooks/get-started.html

What did we just do?

Dora the explorer

KIOfficialArt, CC BY SA 3.0
  1. Create a Quarto Book project in RStudio

  2. Render the Book to html

  3. Turn the project folder into a git repository (more later!)

  4. Upload (“push”) the project files to GitHub

  5. Turn on GitHub pages to publish the html files online

EX: Make a change and publish it

For example:

  • Open the _quarto.yml file and change the title or authors

  • Change or remove some text from one of the chapters

Remember, to upload a change to GitHub:

  1. git add yourfilewithchanges (select which files to make a snapshot of)
  2. git commit -m "Make x change" (create the snapshot with message)
  3. git push (upload to GitHub)

☕ BREAK 1

Markdown

A Markdown introduction

EX: Format some text

Bold, headers, bullet points, links

EX: Embed image, video, pdf

We need to provide the syntax to do this.

EX: Cite the reference from the bib file

We need to tell them how to do this

Git and the git workflow

Explain what git is

Do a round of add-commit-push

Some git terminology

Commit

Pull

Pull request

Merge conflicts

☕ BREAK 2

Interactivity options

  • H5P

  • webexercises R package

  • other options

Publishing and archiving

Archive the repository in Zenodo sandbox